Skip to content

Point the README at 1.0-alpha (#379 follow-up) - #383

Merged
jdatcmd merged 2 commits into
commandprompt:mainfrom
ChronicallyJD:docs/readme-version-alpha
Aug 4, 2026
Merged

Point the README at 1.0-alpha (#379 follow-up)#383
jdatcmd merged 2 commits into
commandprompt:mainfrom
ChronicallyJD:docs/readme-version-alpha

Conversation

@ChronicallyJD

Copy link
Copy Markdown
Collaborator

Follow-up to #379. I raised this on that PR and it landed before the fix, so here it is
separately.

The release shipped with its front page contradicting itself

VERSION reads 1.0-alpha. README.md said:

the version marker is 1.0-dev, recorded in VERSION

That is one click from the file that disagrees with it, in the first paragraph a
visitor reads. The badge said the same thing twice: alt="Version 1.0-dev" and
badges/version.svg rendering version: 1.0-dev.

Fixed

  • README prose and badge alt text now say 1.0-alpha.

  • badges/version.svg regenerated, widened 104 → 118 px because 1.0-alpha is two
    characters longer than 1.0-dev and would otherwise clip.

  • The README now also carries your default_version note, which was only in the
    changelog:

    The extension's own default_version is still 1.0-dev, so
    SELECT extversion FROM pg_extension reports that.

    Keeping that field at 1.0-dev is right and I am not proposing changing it. But the
    front page is where someone hits the surprise, so the explanation belongs there as
    well as in the changelog.

Checked rather than pattern-matched

The one remaining 1.0-dev in README.md is the default_version sentence above, and
it is correct. The PROVENANCE.md occurrences are all about the v1.0-dev tag and
the practice line it preserves — historical fact, untouched.

test/ste_check.py passes on every user-facing document.

Joshua (D) Drake and others added 2 commits August 4, 2026 12:18
1.0-alpha shipped with the front page contradicting the file it links to.
VERSION reads 1.0-alpha; README said "the version marker is 1.0-dev, recorded
in VERSION", one click from the file that disagrees. The badge said the same,
in its alt text and in badges/version.svg.

Raised on commandprompt#379 before the merge and missed in the cut, so this is the follow-up
rather than a new finding.

The README now also carries the default_version note that was only in the
changelog. That field stays 1.0-dev deliberately, because moving it needs an
upgrade script that does not exist, so a user who checks
SELECT extversion FROM pg_extension sees 1.0-dev on a 1.0-alpha build. The
front page is where someone hits that surprise, so the explanation belongs
there too.

The badge SVG is widened from 104 to 118 pixels, because 1.0-alpha is two
characters longer than 1.0-dev and the label would otherwise clip.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
I added a line saying default_version is still 1.0-dev and that extversion
reports it. commandprompt#382's rename needs an upgrade script, so commandprompt#389 bumps
default_version to 1.0-alpha and extversion then agrees with VERSION.

Rather than write a sentence whose truth depends on which PR merges first, the
README now states the version marker and stops there. That reads correctly
before and after commandprompt#389. The default_version detail lives in the changelog and in
docs/installation.md, where the upgrade step it belongs to is documented.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@ChronicallyJD

Copy link
Copy Markdown
Collaborator Author

Updated, because #389 changes the answer.

I had added a sentence saying default_version is still 1.0-dev and that
SELECT extversion reports it. The #382 rename needs an upgrade script, so #389 bumps
default_version to 1.0-alpha, and extversion then agrees with VERSION.

Rather than ship a sentence whose truth depends on merge order, the README now states the
version marker and stops. That reads correctly whichever of these lands first, so the two
PRs are independent again.

The default_version detail moved to the changelog and to docs/installation.md, next
to the upgrade step it belongs with.

ChronicallyJD pushed a commit to ChronicallyJD/pgcolumnar that referenced this pull request Aug 4, 2026
Renaming the C link names orphans every pg_proc row that recorded the old ones.
Replacing only the shared library, which is what a package upgrade does, leaves
the extension inert rather than degraded: reading an existing columnar table
fails with "could not find function columnar_handler", and so does creating a
new one. jdatcmd measured this on commandprompt#389.

There was also no way out. default_version was still 1.0-dev, so ALTER EXTENSION
pgcolumnar UPDATE had nothing to run, and the only remaining route was DROP
EXTENSION CASCADE, which takes the user's tables with it. v1.0-alpha shipped
carrying the old link names, so this is a live install base, not a hypothetical.

My error in the first version of this PR was reading "no upgrade scripts exist"
as "every install is fresh". It means the opposite. With no upgrade script an
existing install has no way to repair itself.

So:

  default_version           1.0-dev -> 1.0-alpha
  pgcolumnar--1.0-dev.sql   renamed to pgcolumnar--1.0-alpha.sql
  new                       pgcolumnar--1.0-dev--1.0-alpha.sql

The upgrade script is 27 CREATE OR REPLACE FUNCTION declarations covering 26
distinct link symbols, vacuum_sorted having two overloads. CREATE OR REPLACE
keeps each function's OID, so the CREATE ACCESS METHOD binding and every
dependency survive and only prosrc moves. No signature, permission, catalog or
on-disk format change.

The declarations are lifted verbatim from the install script rather than
retyped, so the two cannot drift, and the generator refuses to emit anything if
a link name still lacks the new prefix.

This also makes SELECT extversion report 1.0-alpha, matching VERSION. That
contradicts a sentence in my open commandprompt#383, which I will update rather than leave
wrong.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

@jdatcmd jdatcmd left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved, with one follow-on I am taking rather than sending back

Correct in what it changes. The badge geometry is right too: the rect and textLength
grew with the string rather than the label being swapped under a fixed width, which is
the usual way these end up clipped.

The page the badge points at still contradicts it. docs/limitations.md#release-status,
which is the href on the status badge two lines above the one this PR edits, reads:

pgColumnar is pre-release. The version marker is 1.0-dev, recorded in VERSION,
and there has been no tagged release.

Both halves are now wrong, and the second is the one that matters: v1.0-alpha is
tagged and published.
A reader who follows the badge from a README that says
1.0-alpha lands on a page telling them no release exists.

I am fixing that section in a follow-up rather than bouncing this, since it is the
same class of change and I have the facts. Keeping the substance of the guidance --
reloadable tables, not yet a production system of record -- because that is still true
of an alpha; only the "no tagged release" premise goes.

Merging.

@jdatcmd
jdatcmd merged commit 6c694c1 into commandprompt:main Aug 4, 2026
11 checks passed
ChronicallyJD pushed a commit to ChronicallyJD/pgcolumnar that referenced this pull request Aug 4, 2026
Renaming the C link names orphans every pg_proc row that recorded the old ones.
Replacing only the shared library, which is what a package upgrade does, leaves
the extension inert rather than degraded: reading an existing columnar table
fails with "could not find function columnar_handler", and so does creating a
new one. jdatcmd measured this on commandprompt#389.

There was also no way out. default_version was still 1.0-dev, so ALTER EXTENSION
pgcolumnar UPDATE had nothing to run, and the only remaining route was DROP
EXTENSION CASCADE, which takes the user's tables with it. v1.0-alpha shipped
carrying the old link names, so this is a live install base, not a hypothetical.

My error in the first version of this PR was reading "no upgrade scripts exist"
as "every install is fresh". It means the opposite. With no upgrade script an
existing install has no way to repair itself.

So:

  default_version           1.0-dev -> 1.0-alpha
  pgcolumnar--1.0-dev.sql   renamed to pgcolumnar--1.0-alpha.sql
  new                       pgcolumnar--1.0-dev--1.0-alpha.sql

The upgrade script is 27 CREATE OR REPLACE FUNCTION declarations covering 26
distinct link symbols, vacuum_sorted having two overloads. CREATE OR REPLACE
keeps each function's OID, so the CREATE ACCESS METHOD binding and every
dependency survive and only prosrc moves. No signature, permission, catalog or
on-disk format change.

The declarations are lifted verbatim from the install script rather than
retyped, so the two cannot drift, and the generator refuses to emit anything if
a link name still lacks the new prefix.

This also makes SELECT extversion report 1.0-alpha, matching VERSION. That
contradicts a sentence in my open commandprompt#383, which I will update rather than leave
wrong.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ChronicallyJD pushed a commit to ChronicallyJD/pgcolumnar that referenced this pull request Aug 4, 2026
…iew)

Reviewing jdatcmd's commandprompt#392 turned up a second copy of the instruction I rewrote
in docs/installation.md, 85 lines below the paragraph that PR fixes.

limitations.md said the pre-release ships no ALTER EXTENSION UPDATE scripts,
which this branch makes false, and then told the reader they can replace the
shared library and restart without one. That is precisely the sequence that
leaves the extension inert. It then pointed at DROP EXTENSION, which takes the
user's columnar tables with it.

A user who hits the broken state and follows the status badge lands on that
page, so it was the worst remaining copy.

The paragraph now states that replacing the library is not sufficient on its
own, gives the command, explains why an un-updated catalog fails and with which
error, and says plainly that the data is untouched. The DROP EXTENSION paragraph
is scoped to a build no upgrade script covers, and says it is not the remedy for
this case.

I missed this in commandprompt#383 and again when I rewrote installation.md. Sweeping for a
second copy is the step I skipped both times.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jdatcmd added a commit that referenced this pull request Aug 4, 2026
The release-status page said no release was tagged (#383 follow-up)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants